home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kxmlguifactory.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  8.4 KB  |  221 lines
  1. // -*- mode: c++; c-basic-offset: 2 -*-
  2. /* This file is part of the KDE libraries
  3.    Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
  4.    Copyright (C) 2000 Kurt Granroth <granroth@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License version 2 as published by the Free Software Foundation.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef __kxmlguifactory_h__
  22. #define __kxmlguifactory_h__
  23.  
  24. #include <qobject.h>
  25. #include <qptrlist.h>
  26. #include <qdom.h>
  27. #include <qvaluelist.h>
  28.  
  29. #include <kdelibs_export.h>
  30.  
  31. class KAction;
  32. class KXMLGUIFactoryPrivate;
  33. class KXMLGUIClient;
  34. class KXMLGUIBuilder;
  35. class KInstance;
  36.  
  37. namespace KXMLGUI
  38. {
  39. struct MergingIndex;
  40. struct ContainerNode;
  41. struct ContainerClient;
  42. class BuildHelper;
  43. }
  44.  
  45. /**
  46.  * KXMLGUIFactory, together with KXMLGUIClient objects, can be used to create
  47.  * a GUI of container widgets (like menus, toolbars, etc.) and container items
  48.  * (menu items, toolbar buttons, etc.) from an XML document and action objects.
  49.  *
  50.  * Each KXMLGUIClient represents a part of the GUI, composed from containers and
  51.  * actions. KXMLGUIFactory takes care of building (with the help of a KXMLGUIBuilder)
  52.  * and merging the GUI from an unlimited number of clients.
  53.  *
  54.  * Each client provides XML through a QDomDocument and actions through a
  55.  * KActionCollection . The XML document contains the rules for how to merge the
  56.  * GUI.
  57.  *
  58.  * KXMLGUIFactory processes the DOM tree provided by a client and plugs in the client's actions,
  59.  * according to the XML and the merging rules of previously inserted clients. Container widgets
  60.  * are built via a KXMLGUIBuilder , which has to be provided with the KXMLGUIFactory constructor.
  61.  */
  62. class KDEUI_EXPORT KXMLGUIFactory : public QObject
  63. {
  64.   friend class KXMLGUI::BuildHelper;
  65.   Q_OBJECT
  66.  public:
  67.   /**
  68.    * Constructs a KXMLGUIFactory. The provided @p builder KXMLGUIBuilder will be called
  69.    * for creating and removing container widgets, when clients are added/removed from the GUI.
  70.    *
  71.    * Note that the ownership of the given KXMLGUIBuilder object won't be transferred to this
  72.    * KXMLGUIFactory, so you have to take care of deleting it properly.
  73.    */
  74.   KXMLGUIFactory( KXMLGUIBuilder *builder, QObject *parent = 0, const char *name = 0 );
  75.  
  76.   /**
  77.    * Destructor
  78.    */
  79.   ~KXMLGUIFactory();
  80.  
  81.   // XXX move to somewhere else? (Simon)
  82.   static QString readConfigFile( const QString &filename, bool never_null, const KInstance *instance = 0 );
  83.   static QString readConfigFile( const QString &filename, const KInstance *instance = 0 );
  84.   static bool saveConfigFile( const QDomDocument& doc, const QString& filename,
  85.                               const KInstance *instance = 0 );
  86.  
  87.   static QString documentToXML( const QDomDocument& doc );
  88.   static QString elementToXML( const QDomElement& elem );
  89.  
  90.   /**
  91.    * Removes all QDomComment objects from the specified node and all its children.
  92.    */
  93.   static void removeDOMComments( QDomNode &node );
  94.  
  95.   /**
  96.    * @internal
  97.    * Find or create the ActionProperties element, used when saving custom action properties
  98.    */
  99.   static QDomElement actionPropertiesElement( QDomDocument& doc );
  100.  
  101.   /**
  102.    * @internal
  103.    * Find or create the element for a given action, by name.
  104.    * Used when saving custom action properties
  105.    */
  106.   static QDomElement findActionByName( QDomElement& elem, const QString& sName, bool create );
  107.  
  108.   /**
  109.    * Creates the GUI described by the QDomDocument of the client,
  110.    * using the client's actions, and merges it with the previously
  111.    * created GUI.
  112.    * This also means that the order in which clients are added to the factory
  113.    * is relevant; assuming that your application supports plugins, you should
  114.    * first add your application to the factory and then the plugin, so that the
  115.    * plugin's UI is merged into the UI of your application, and not the other
  116.    * way round.
  117.    */
  118.   void addClient( KXMLGUIClient *client );
  119.  
  120.   /**
  121.    * Removes the GUI described by the client, by unplugging all
  122.    * provided actions and removing all owned containers (and storing
  123.    * container state information in the given client)
  124.    */
  125.   void removeClient( KXMLGUIClient *client );
  126.  
  127.   void plugActionList( KXMLGUIClient *client, const QString &name, const QPtrList<KAction> &actionList );
  128.   void unplugActionList( KXMLGUIClient *client, const QString &name );
  129.  
  130.   /**
  131.    * Returns a list of all clients currently added to this factory
  132.    */
  133.   QPtrList<KXMLGUIClient> clients() const;
  134.  
  135.   /**
  136.    * Use this method to get access to a container widget with the name specified with @p containerName
  137.    * and which is owned by the @p client. The container name is specified with a "name" attribute in the
  138.    * XML document.
  139.    *
  140.    * This function is particularly useful for getting hold of a popupmenu defined in an XMLUI file.
  141.    * For instance:
  142.    * \code
  143.    * QPopupMenu *popup = static_cast<QPopupMenu*>(factory()->container("my_popup",this));
  144.    * \endcode
  145.    * where @p "my_popup" is the name of the menu in the XMLUI file, and
  146.    * @p "this" is XMLGUIClient which owns the popupmenu (e.g. the mainwindow, or the part, or the plugin...)
  147.    *
  148.    * @param containerName Name of the container widget
  149.    * @param client Owner of the container widget
  150.    * @param useTagName Specifies whether to compare the specified name with the name attribute or
  151.    *        the tag name.
  152.    *
  153.    * This method may return 0L if no container with the given name exists or is not owned by the client.
  154.    */
  155.   QWidget *container( const QString &containerName, KXMLGUIClient *client, bool useTagName = false );
  156.  
  157.   QPtrList<QWidget> containers( const QString &tagName );
  158.  
  159.   /**
  160.    * Use this method to free all memory allocated by the KXMLGUIFactory. This deletes the internal node
  161.    * tree and therefore resets the internal state of the class. Please note that the actual GUI is
  162.    * NOT touched at all, meaning no containers are deleted nor any actions unplugged. That is
  163.    * something you have to do on your own. So use this method only if you know what you are doing :-)
  164.    *
  165.    * (also note that this will call KXMLGUIClient::setFactory( 0L ) for all inserted clients)
  166.    */
  167.   void reset();
  168.  
  169.   /**
  170.    * Use this method to free all memory allocated by the KXMLGUIFactory for a specific container,
  171.    * including all child containers and actions. This deletes the internal node subtree for the
  172.    * specified container. The actual GUI is not touched, no containers are deleted or any actions
  173.    * unplugged. Use this method only if you know what you are doing :-)
  174.    *
  175.    * (also note that this will call KXMLGUIClient::setFactory( 0L ) for all clients of the
  176.    * container)
  177.    */
  178.   void resetContainer( const QString &containerName, bool useTagName = false );
  179.  
  180.  public slots:
  181.   /**
  182.    * Show a standard configure shortcut for every action in this factory.
  183.    *
  184.    * This slot can be connected dirrectly to the action to configure shortcuts. This is very simple to
  185.    * do that by adding a single line
  186.    * \code
  187.    * KStdAction::keyBindings( guiFactory(), SLOT( configureShortcuts() ), actionCollection() );
  188.    * \endcode
  189.    *
  190.    * @param bAllowLetterShortcuts Set to false if unmodified alphanumeric
  191.    *      keys ('A', '1', etc.) are not permissible shortcuts.
  192.    * @param bSaveSettings if true, the settings will also be saved back to
  193.    *      the *uirc file which they were intially read from.
  194.    * @since 3.3
  195.    */
  196.   int configureShortcuts(bool bAllowLetterShortcuts = true, bool bSaveSettings = true);
  197.  
  198.  signals:
  199.   void clientAdded( KXMLGUIClient *client );
  200.   void clientRemoved( KXMLGUIClient *client );
  201.  
  202.  private:
  203.  
  204.   QWidget *findRecursive( KXMLGUI::ContainerNode *node, bool tag );
  205.  
  206.   QPtrList<QWidget> findRecursive( KXMLGUI::ContainerNode *node, const QString &tagName );
  207.  
  208.   void applyActionProperties( const QDomElement &element );
  209.   void configureAction( KAction *action, const QDomNamedNodeMap &attributes );
  210.   void configureAction( KAction *action, const QDomAttr &attribute );
  211.  
  212. protected:
  213.   virtual void virtual_hook( int id, void* data );
  214. private:
  215.   KXMLGUIFactoryPrivate *d;
  216. };
  217.  
  218. #endif
  219. /* vim: et sw=4
  220.  */
  221.